<!DOCTYPE html><html><head>
<title>critcl_install_guide - C Runtime In Tcl (CriTcl)</title>
<style type="text/css"><!--
    HTML {
	background: 	#FFFFFF;
	color: 		black;
    }
    BODY {
	background: 	#FFFFFF;
	color:	 	black;
    }
    DIV.doctools {
	margin-left:	10%;
	margin-right:	10%;
    }
    DIV.doctools H1,DIV.doctools H2 {
	margin-left:	-5%;
    }
    H1, H2, H3, H4 {
	margin-top: 	1em;
	font-family:	sans-serif;
	font-size:	large;
	color:		#005A9C;
	background: 	transparent;
	text-align:		left;
    }
    H1.doctools_title {
	text-align: center;
    }
    UL,OL {
	margin-right: 0em;
	margin-top: 3pt;
	margin-bottom: 3pt;
    }
    UL LI {
	list-style: disc;
    }
    OL LI {
	list-style: decimal;
    }
    DT {
	padding-top: 	1ex;
    }
    UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
	font:		normal 12pt/14pt sans-serif;
	list-style:	none;
    }
    LI.doctools_section, LI.doctools_subsection {
	list-style: 	none;
	margin-left: 	0em;
	text-indent:	0em;
	padding: 	0em;
    }
    PRE {
	display: 	block;
	font-family:	monospace;
	white-space:	pre;
	margin:		0%;
	padding-top:	0.5ex;
	padding-bottom:	0.5ex;
	padding-left:	1ex;
	padding-right:	1ex;
	width:		100%;
    }
    PRE.doctools_example {
	color: 		black;
	background: 	#f5dcb3;
	border:		1px solid black;
    }
    UL.doctools_requirements LI, UL.doctools_syntax LI {
	list-style: 	none;
	margin-left: 	0em;
	text-indent:	0em;
	padding:	0em;
    }
    DIV.doctools_synopsis {
	color: 		black;
	background: 	#80ffff;
	border:		1px solid black;
	font-family:	serif;
	margin-top: 	1em;
	margin-bottom: 	1em;
    }
    UL.doctools_syntax {
	margin-top: 	1em;
	border-top:	1px solid black;
    }
    UL.doctools_requirements {
	margin-bottom: 	1em;
	border-bottom:	1px solid black;
    }
--></style>
</head>
<!-- Generated from file 'critcl_installer.man' by tcllib/doctools with format 'html'
   -->
<!-- Copyright &amp;copy; Jean-Claude Wippler   -- Copyright &amp;copy; Steve Landers   -- Copyright &amp;copy; 2011-2018 Andreas Kupries
   -->
<!-- critcl_install_guide.n
   -->
<body><hr> [
   <a href="../toc.html">Table Of Contents</a>
| <a href="../index.html">Keyword Index</a>
 ] <hr>
<div class="doctools">
<h1 class="doctools_title">critcl_install_guide(n) 3.1.18.1 doc &quot;C Runtime In Tcl (CriTcl)&quot;</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>critcl_install_guide - Critcl - The Installer's Guide</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Requisites</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Tcl</a></li>
<li class="doctools_subsection"><a href="#subsection2">Tcllib</a></li>
<li class="doctools_subsection"><a href="#subsection3">C compiler</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section3">Build &amp; Installation Instructions</a>
<ul>
<li class="doctools_subsection"><a href="#subsection4">Build &amp; Installation (Unix)</a></li>
<li class="doctools_subsection"><a href="#subsection5">Build &amp; Installation (Windows)</a></li>
<li class="doctools_subsection"><a href="#subsection6">First Use, Testing the Installation</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section4">Authors</a></li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p><i class="term">C Runtime In Tcl</i>, or <i class="term"><a href="critcl_pkg.html">CriTcl</a></i> , is a system for compiling C code
embedded in Tcl on the fly and either loading the resulting objects into Tcl for
immediate use or packaging them for distribution.  Use <i class="term"><a href="critcl_pkg.html">CriTcl</a></i> to improve
performance by rewriting in C those routines that are performance bottlenecks.</p>
<p>The audience of this document is anyone wishing to build the
packages, for either themselves, or others.</p>
<p>For a developer intending to extend or modify the packages we
additionally provide</p>
<ol class="doctools_enumerated">
<li><p><i class="term"><a href="license.html">Critcl - License</a></i>.</p></li>
<li><p><i class="term"><a href="critcl_devguide.html">Critcl - The Developer's Guide</a></i>.</p></li>
</ol>
<p>Please read <i class="term"><a href="critcl_sources.html">Critcl - How To Get The Sources</a></i> first, if that was
not done already. Here we assume that the sources are already
available in a directory of your choice.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Requisites</a></h2>
<p>Before Critcl can be build and used a number of requisites must be installed. These are:</p>
<ol class="doctools_enumerated">
<li><p>The scripting language Tcl.
       For details see <span class="sectref"><a href="#subsection1">Tcl</a></span>.</p></li>
<li><p>Various packages from the Tcllib bundle for <b class="syscmd">Tcl</b>.
       For details see <span class="sectref"><a href="#subsection2">Tcllib</a></span>.</p></li>
<li><p>A working C compiler and development environment.</p></li>
</ol>
<p>This list assumes that the machine where Critcl is to be installed is
essentially clean. Of course, if parts of the dependencies listed
below are already installed the associated steps can be skipped. It is
still recommended to read their sections though, to validate that the
dependencies they talk about are indeed installed.</p>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Tcl</a></h3>
<p>As we are building a Tcl package that should be pretty much obvious
that a working Tcl installation is needed, and I will not belabor the
point.</p>
<p>Out of the many use whatever you are comfortable with, as long
as it provides Tcl 8.5, or higher, and Tk 8.5 or higher.</p>
<p>This may a Tcl installation provided by your operating system
distribution, from a distribution-independent vendor, or built by
yurself.</p>
<p>Myself, I used <a href="http://www.activestate.com">ActiveState's</a>
ActiveTcl 8.5 distribution during development of the binding, as I am
most familiar with it.</p>
<p><em>(Disclosure: I, Andreas Kupries, work for ActiveState, maintaining ActiveTcl and TclDevKit for them).</em></p>
<p>This distribution can be found at
<a href="http://www.activestate.com/activetcl">http://www.activestate.com/activetcl</a>. Retrieve the archive of
ActiveTcl 8.5 for your platform and install it as directed by
ActiveState.</p>
<p>Assuming that ActiveTcl got installed I usually run the command</p>
<pre class="doctools_example">
    teacup update
</pre>
<p>to install all packages ActiveState provides, and the kitchensink, as
the distribution itself usually contains only the ost important set of
packages. This ensures that the dependencies for Critcl are all
present, and more.</p>
<p>If that is not to your liking you have to read the sections for
Critcl to determine the exact set of packages required, and install
only these using</p>
<pre class="doctools_example">
    teacup install $packagename
</pre>
<p>Both <b class="syscmd">teacup</b> commands above assume that ActiveState's
TEApot repository at <a href="http://teapot.activestate.com">http://teapot.activestate.com</a> is in the
list of repositories accessible to <b class="syscmd">teacup</b>. This is automatically
ensured for the ActiveTcl distribution. Others may have to run</p>
<pre class="doctools_example">
    teacup archive add http://teapot.activestate.com
</pre>
<p>to make this happen.</p>
<p>For those wishing to build Tcl/Tk on their own, their sources
can be found at</p>
<dl class="doctools_definitions">
<dt>Tcl</dt>
<dd><p><a href="http://core.tcl.tk/tcl/">http://core.tcl.tk/tcl/</a></p></dd>
<dt>Tk</dt>
<dd><p><a href="http://core.tcl.tk/tk/">http://core.tcl.tk/tk/</a></p></dd>
</dl>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Tcllib</a></h3>
<p>To use Critcl a few packages found in the Tcllib bundle are
required. These packages are:</p>
<ol class="doctools_enumerated">
<li><p><b class="package">cmdline</b></p></li>
<li><p><b class="package">md5</b>.</p>
<p>And to accelerate this package, it is recommend to get and
install one of</p>
<ol class="doctools_enumerated">
<li><p><b class="package">tcllibc</b></p></li>
<li><p><b class="package">md5c</b></p></li>
<li><p><b class="package">Trf</b></p></li>
</ol>
<p>The system will work without them, but can become quite slow,
especially when handling large code blocks.</p></li>
<li><p><b class="package">snit</b></p></li>
</ol>
<p>Assuming that ActiveTcl is installed, or some other Tcl
installation with <b class="syscmd">teacup</b> available, most (not md5c) of these
packages can be installed via</p>
<pre class="doctools_example">
    teacup install $packagename
</pre>
<p>The <b class="syscmd">teacup</b> command above assumes that ActiveState's
TEApot repository at <a href="http://teapot.activestate.com">http://teapot.activestate.com</a> is in the
list of repositories accessible to <b class="syscmd">teacup</b>. This is automatically
ensured for the ActiveTcl distribution. Others may have to run</p>
<pre class="doctools_example">
    teacup archive add http://teapot.activestate.com
</pre>
<p>to make this happen.</p>
<p>Now, for those wishing to install the packages from source,
the fossil repository for the two bundles can be found at
<a href="https://core.tcl.tk/tcllib">https://core.tcl.tk/tcllib</a> and <a href="https://core.tcl.tk/tklib">https://core.tcl.tk/tklib</a>.</p>
<p>Releases of Tcllib and Tklib can be found there as well, or
<b class="syscmd">fossil</b> can be used to check out specific revisions.</p>
<p>Tcl- and Tklib come with their own installation instructions.
These will not be repeated here. If there are problems with their
directions please file a bug against the Tcllib project at the above
url, and not CriTcl.</p>
</div>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">C compiler</a></h3>
<p>To actually build packages based on critcl we need a working C
compiler.</p>
<p>How to install such and all the associated header files,
libraries, etc. is heavily platform- and system-dependent, and thus
outside of the scope of this document.
Note that I am willing to extend this section with links of interest
to tutorials, howtos and references for the various platforms.</p>
<p>The important pieces of information are this:</p>
<ol class="doctools_enumerated">
<li><p>The path to the C compiler binary must be found in the
	environment variable <b class="variable">PATH</b>, for critcl to find it.</p></li>
<li><p>On Windows(tm) the environment variable <b class="variable">LIB</b> must be
	present and contain the paths of the directories holding
	Microsoft's libraries. The standard critcl configuration
	for this platform searches these paths to fine-tune its
	settings based on available libraries and compiler version.</p></li>
</ol>
<p>Links of interest:</p>
<dl class="doctools_definitions">
<dt><a href="http://www.tldp.org/HOWTO/HOWTO-INDEX/programming.html">http://www.tldp.org/HOWTO/HOWTO-INDEX/programming.html</a></dt>
<dd></dd>
</dl>
</div>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Build &amp; Installation Instructions</a></h2>
<div id="subsection4" class="doctools_subsection"><h3><a name="subsection4">Build &amp; Installation (Unix)</a></h3>
<p>This section describes the actions required to install CriTcl on Unix
systems (Linux, BSD, and related, including OS X).
If you have to install CriTcl on a Windows machine see section
<span class="sectref"><a href="#subsection5">Build &amp; Installation (Windows)</a></span> instead.
To install Critcl simply run</p>
<pre class="doctools_example">
    /path/to/tclsh /path/to/critcl/build.tcl install
</pre>
<p>where &quot;<b class="file">/path/to/tclsh</b>&quot; is the tclsh of your Tcl installation, and
&quot;<b class="file">/path/to/critcl</b>&quot; the location of the Critcl sources on your system.</p>
<p>This builds all packages and then places them in a directory where the
<b class="cmd">tclsh</b> will find them.</p>
<p>It further creates a &quot;<b class="file">critcl</b>&quot; application script and places it
into the directory <b class="cmd">tclsh</b> resides in, making it a sibling of that
executable.
Note that the installed critcl application is modified to use the
chosen tclsh instead of searching for one on the <b class="variable">PATH</b>.</p>
<p>On Windows you can invoke the file &quot;<b class="file">build.tcl</b>&quot; with a
double-click.  This will pop up a small graphical interface for
entering the destination and performing the installation. This
handling of a double-click is restricted to Windows only however.</p>
<p>The build system provides a small GUI for those not comfortable with
the command line.
This GUI is accessible by invoking &quot;<b class="file">build.tcl</b>&quot; without any
arguments.</p>
<p>To get help about the methods of &quot;<b class="file">build.tcl</b>&quot;, and their complete
syntax, invoke  &quot;<b class="file">build.tcl</b>&quot; with argument <b class="method">help</b>, i.e., like</p>
<pre class="doctools_example">
    /path/to/tclsh /path/to/critcl/build.tcl help
</pre>
</div>
<div id="subsection5" class="doctools_subsection"><h3><a name="subsection5">Build &amp; Installation (Windows)</a></h3>
<p>This section describes the actions required to install CriTcl on
Windows(tm) systems.
If you have to install CriTcl on a Unix machine (Linux, BSD, and
related, including OS X) see section
<span class="sectref"><a href="#subsection4">Build &amp; Installation (Unix)</a></span> instead.
To install Critcl simply run</p>
<pre class="doctools_example">
    /path/to/tclsh /path/to/critcl/build.tcl install
</pre>
<p>where &quot;<b class="file">/path/to/tclsh</b>&quot; is the tclsh of your Tcl installation, and
&quot;<b class="file">/path/to/critcl</b>&quot; the location of the Critcl sources on your system.</p>
<p>This builds all packages and then places them in a directory where the
<b class="cmd">tclsh</b> will find them.</p>
<p>It further creates a &quot;<b class="file">critcl</b>&quot; application script and places it
into the directory <b class="cmd">tclsh</b> resides in, making it a sibling of that
executable.</p>
<p><em>Attention!</em> Note that while the installed critcl
application is modified to use the chosen tclsh instead of searching
for one on the <b class="variable">PATH</b> this is useless for Windows, which
associates executables with files through their extension.</p>
<p><em>Attention!</em> The current installer does not put an
extension on the <b class="syscmd"><a href="critcl_pkg.html">critcl</a></b> application, forcing users to either
explicitly choose the <b class="syscmd">tclsh</b> to run the application, or
manually rename the installed file to &quot;<b class="file">critcl.tcl</b>&quot;, if an
association for &quot;<b class="file">.tcl</b>&quot; is available, to either <b class="syscmd">tclsh</b>, or
<b class="syscmd">wish</b>.</p>
<p>On Windows you can invoke the file &quot;<b class="file">build.tcl</b>&quot; with a
double-click.  This will pop up a small graphical interface for
entering the destination and performing the installation. This
handling of a double-click is restricted to Windows only however.</p>
<p>This GUI is also accessible by invoking &quot;<b class="file">build.tcl</b>&quot; without any
arguments.</p>
<p>To get help about the methods of &quot;<b class="file">build.tcl</b>&quot;, and their complete
syntax, invoke  &quot;<b class="file">build.tcl</b>&quot; with argument <b class="method">help</b>, i.e., like</p>
<pre class="doctools_example">
    /path/to/tclsh /path/to/critcl/build.tcl help
</pre>
</div>
<div id="subsection6" class="doctools_subsection"><h3><a name="subsection6">First Use, Testing the Installation</a></h3>
<p>With critcl installed it is now the time to try at least one of the
examples distributed with it. This will also test if the installation
was successful.</p>
<p>Below I show the steps to generate and then use the low- and
high-level stack example packages. I am intentionally bypassing the
&quot;<b class="file">build.tcl</b>&quot; file the example is coming with, to show the use of
<b class="cmd"><a href="critcl_pkg.html">critcl</a></b> itself.</p>
<p>Some more explanations before running the example:</p>
<ul class="doctools_itemized">
<li><p>Here &quot;<b class="file">path/to/critcl</b>&quot; is the path to the installed
	critcl application, not the critcl source directory.</p>
<p>Also, on Windows(tm) this part of the example must be
	replaced with</p>
<pre class="doctools_example"> /path/to/tclsh /path/to/critcl </pre>
<p>as the installed application has no extension and
	thus Windows will not know how to execute the script.</p>
<p>Only if the installed application was manually renamed to
	&quot;<b class="file">critcl.tcl</b>&quot; and the machine has an association for
	&quot;<b class="file">.tcl</b>&quot; to either <b class="syscmd">tclsh</b> or <b class="syscmd">wish</b> then
	the &quot;<b class="file">/path/to/tclsh</b>&quot; can be left out.</p></li>
<li><p>The example shows only the commands entered on the shell (and
	tclsh) command line. Their responses are left out.</p>
<p>If any command throws an error, i.e. has a problem, then all
	following commands will run into some other error as well,
	as a consequence of the first problem.</p></li>
<li><p>Use of option <b class="option">-keep</b> causes critcl to leave the
	generated .c files behind, for edification. Normally this
	happens only in case of trouble.</p></li>
<li><p>Use of option <b class="option">-cache</b> redirects the location of the
	directory to hold generated and build files to a local
	directory with a known name, for an easy look after.</p></li>
<li><p>Both <b class="package">cstack</b> and <b class="package">stackc</b> have to use the
	<em>same</em> <b class="option">-cache</b> so that <b class="package">stackc</b> will
	find the stub table headers exported by <b class="package">cstack</b>.</p></li>
</ul>
<pre class="doctools_example">
    &gt; cd examples/stack
    &gt; /path/to/critcl -keep -cache B -pkg cstack.tcl
    &gt; /path/to/critcl -keep -cache B -pkg stackc.tcl
    &gt; tclsh
    % lappend auto_path [pwd]/lib
    % package require stackc
    % join [info loaded] \n
    % stackc S
    % S push FOO
    % S size
    % S destroy
    % exit
    &gt;
</pre>
</div>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Authors</a></h2>
<p>Jean Claude Wippler, Steve Landers, Andreas Kupries</p>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report them at <a href="https://github.com/andreas-kupries/critcl/issues">https://github.com/andreas-kupries/critcl/issues</a>.
Ideas for enhancements you may have for either package, application,
and/or the documentation are also very welcome and should be reported
at <a href="https://github.com/andreas-kupries/critcl/issues">https://github.com/andreas-kupries/critcl/issues</a> as well.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../index.html#key8">C code</a>, <a href="../index.html#key3">Embedded C Code</a>, <a href="../index.html#key6">code generator</a>, <a href="../index.html#key0">compile &amp; run</a>, <a href="../index.html#key10">compiler</a>, <a href="../index.html#key1">dynamic code generation</a>, <a href="../index.html#key2">dynamic compilation</a>, <a href="../index.html#key9">generate package</a>, <a href="../index.html#key4">linker</a>, <a href="../index.html#key5">on demand compilation</a>, <a href="../index.html#key7">on-the-fly compilation</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Glueing/Embedded C code</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright &copy; Jean-Claude Wippler<br>
Copyright &copy; Steve Landers<br>
Copyright &copy; 2011-2018 Andreas Kupries</p>
</div>
</div></body></html>
